SPACE 1/SPACE - Library 1 - Volume 1.iso/program/505/install.doc

Text File | 1991-08-22 | 30KB | 626 lines

         Welcome to Ian's Heat-and-Serve release of Sozobon C!
            This release is version 1.31i, dated 07/28/91


         ***************************************************
         *    THIS IS A MODIFIED VERSION OF SOZOBON C!     *
         *                                                 *
         * This version has been customized by Ian Lepore, *
         * and is NOT an official release of Sozobon, Ltd. *
         * Please do NOT direct any bug reports or support *
         * questions for this release to the good folks at *
         *     Sozobon...if anything goes wrong, it's      *
         *                 Not Their Fault.                *
         ***************************************************


CONTENTS

    1.0     Overview
    1.1       Last Minute Fixes

    2.0     Installation
    2.1       Notes for Floppy Disk Installation
    2.2       The INSTALL Program
    2.3       The GEMENV Program
    2.4       Desktop Installation Procedure
    2.5       CLI Installation Procedure

    3.0     In Case of Difficulties
    3.1       Trouble with MAKE
    3.2       Trouble with Environment Variables

    4.0     Roadmap (Directory and File List)

    5.0     Credits and disclaimers


1.0 Overview


    I have dubbed this the 'Heat-and-Serve' release, because unlike
    previous Sozobon releases, this one virtually installs itself, and
    it works right away, without the need for a lot of customization.
    In addition to the easier installation, this release differs from
    the original Sozobon C v1.0 and 1.2 releases in the following ways:

    -   The compiler now speaks English instead of technish when
        reporting errors.  (LD still tends to be cryptic).

    -   A desktop-friendly MAKE utility is included, as well as other
        assists for the desktop user.

    -   The compiler pieces and MAKE utility are smarter about where
        to look for files in the absence of PATH= information.

    -   Several code generation bugs were fixed in the compiler.  Also,
        several ANSI features were added, such as concatenation of
        adjacent string literals.

    -   The TOP optimizer is vastly improved in terms of the peephole
        optimizations it does.

    -   The compiler controller (CC) program now knows how to use a
        ramdisk to hold intermediate files, for better performance.
        (Floppy disk users especially benefit from this.)

    -   Lots of performance tweaks; in particular, intelligent I/O
        buffering has been added to the compiler pieces, and the
        assembler is 50-100% faster.

    -   All libraries and runtime supports are included in the
        distribution, including the GemFast libraries for GEM
        programming, and a variety of runtime startup files for
        different environments.

    -   This release does NOT include source code (except for the
        runtime startup files and example programs.)  The next release
        will include full source code.


1.1 Last Minute Fixes


    A limited released of v1.30 was done, and within a week had generated
    several bug reports (thank you to Steve Yelvington, Mike Dorman, and
    Bob Goff for the reports!)  Here's a quick summary of the differences
    between the 1.30 and 1.31 release.  Note that the documentation in the
    DOCS directory has NOT been updated to reflect these fixes!

    - If the INSTALL program was run from within a folder, it would
      create the \sozobon directory tree inside the folder instead of
      at the root like it's supposed to.  Now it works correctly when
      run from within a folder.

    - The compiler pieces, and any programs generated with them, would
      still bomb under GEMINI or anything else that uses the xArgs
      protocol to pass runtime args to programs; this was in spite of
      the fact that I applied the fixes I was given into dlibs.a.  It
      turns out that the real problem was the infamous JAS bug that
      generated bad binary code for the BTST, BSET, BCLR, and BCHG
      instructions.  I could have tweaked the library bzero() and memcpy()
      code to eliminate use of those instructions, but instead I just bit
      the bullet and fixed the problem in JAS.  The JAS version is now
      v1.26, and it now handles all forms and addressing modes of the
      bit operation instructions listed above.


2.0 Installation


    This release of Sozobon C is supplied as a single archive file
    which contains everything needed to set up the compiler and begin
    writing programs immediately.  There is no need for you to obtain
    other support files from your network or BBS.

    When unpacking the distribution archive (the one that contained
    this file), it is important that all the files that came out of
    it remain together in the same folder.  If any of the files are
    missing, the installation program may not be able to perform all
    the installation steps (it will whine at you).  When the
    distribution archive is unpacked, the following files emerge:

        INSTALL.DOC     - This document.
        INSTALL.PRG     - The installation utility.
        GEMENV.PRG      - Environment variable manager.
        SCBIN130.PDF    - The compiler itself, in packed format.
        SCDOC130.PDF    - The full documention, in packed format.
        SCXMP130.PDF    - The example source code, in packed format.

    After reviewing the installation notes below, all you need to do
    is run INSTALL.PRG to install and configure the compiler.  The
    installation program uses GEM, so it must be run from the desktop
    or a shell which supports GEM programs.  The compiler itself does
    not require GEM or desktop usage once it's installed.

    The install program will prompt you for which installation steps
    you wish to run, and which drives or hard disk partitions you wish
    to install the parts of the compiler on.  There are three separate
    packed data files to accomodate floppy disk users.  It is assumed
    that hard disk users will generally unpack all three data files
    to the same partition, so the INSTALL program will pre-set its
    buttons for that situation.  This is optional, however.  The files
    unpacked from the SCBINxxx.PDF file MUST ALWAYS remain together on
    the same drive, but the documentation and examples can go anywhere.

    The packed data files will require disk space to unpack as follows:

        SCBIN130.PDF  =   428 KBytes
        SCDOC130.PDF  =   321 KBytes
        SCXMP130.PDF  =    46 KBytes
        ----------------------------
        Total         =   795 KBytes

    Note that when names of the form "x:\PATH" appear in the notes below
    the 'x' should be filled in with the drive onto which you unpacked
    the compiler (the SCBINxxx.PDF file).


2.1 Notes for Floppy Disk Installation


    Floppy disk installation (to a double-sided drive) is possible,
    providing that a ramdisk or second floppy drive is available to
    hold the packed data files while they are being unpacked to the
    target floppy disk.  The full distribution more than fills a
    normal double-sided disk when unpacked.

    The install program will allow you to unpack each of the packed
    data files to a different disk to alleviate this problem.  (When
    the target drive is A or B, the program will prompt you to change
    disks between each unpack step.  You may change disks, or simply
    click on CONTINUE to use the same disk for the next step.)

    For floppy disk installation, start with an empty DS floppy, and
    create an AUTO folder.  Put a copy of your DESKTOP.INF file in the
    root directory.  Do these steps before running the installation
    program.  If you are going to unpack the data files to separate
    disks, only the compiler disk itself needs to have an AUTO folder
    and a DESKTOP.INF file on it; the disks for the documentation and
    example code files can be any pre-formatted floppy disk with enough
    free space to hold the unpacked files.

    For systems with a single floppy drive, and a smallish ramdisk, it
    is possible to perform the installation in several steps.  Copy
    INSTALL.PRG, SCBINxxx.PDF, and GEMENV.PRG to the ramdisk, and run
    the install program.  (It will whine about missing files.)  Run the
    steps of the install which are not disabled.  When the steps are
    done, remove SCBINxxx.PDF from the ramdisk and copy SCDOCxxx.PDF
    to the ramdisk, and run the install program again.  Perform these
    steps again for SCXMPxxx.PDF.

    After preparing your floppy disks, Follow either the Desktop or
    CLI procedure below, depending on the way you intend to use Sozobon.


2.2 The INSTALL Program


    This program will present a dialog box that describes the steps
    of the installation, and has a drive button next to each step.
    You may click on the drive button for any step to change the
    target drive or set that step to be bypassed completely.  After
    setting the drive buttons appropriately, click on the PROCEED
    button to run the installation steps which were not set for bypass.
    Even after clicking on PROCEED, you will be prompted for one more
    chance to stop the installation before any data is unpacked or any
    of your system files are modified.  The install program takes the
    following steps (assuming none are bypassed):

    1.  Install the compiler.  This step unpacks the contents of
        SCBINxxx.PDF to the indicated drive.  The unpacking process
        will create a \SOZOBON folder in the root of the target drive,
        and will create other folders within \SOZOBON.  When this option
        is active (ie, not bypassed), you will be prompted for two
        additional parameters after clicking on PROCEED, the I/O buffer
        size, and the device for temporary files.  Both of these options
        are entered via GEM dialog boxes which contain a description of
        the parameters and recommended settings.

    2.  Install the documentation.  This step unpacks the contents of
        SCDOCxxx.PDF to the indicated drive.

    3.  Install the example programs.  This step unpacks the contents
        of SCXMPxxx.PDF to the indicated drive.

    4.  Install GEMENV.PRG into the AUTO folder on the indicated drive.
        The GEMENV program is described below.  If you are using the
        standard GEM desktop, or DCDesktop, you must run this step.
        If you are using a CLI, GEMINI, NeoDesk, or other alternate
        desktops that have builtin support for environment variables,
        you may bypass this step, and manually configure your env
        variables to the values described in the CLI installation
        process, in section 2.5 step 3.

    5.  Modify the DESKTOP.INF file on the indicated drive to install
        MAKE.TTP as the application to handle double-clicks on files
        ending in .MAK.  If you are using the GEM desktop or DCDesktop,
        you may run this step, or take the corresponding action
        manually.  If you are running a different alternate desktop, you
        will need to follow whatever procedure exists for that desktop
        to install an application to handle double-clicks on .MAK files.
        If you will be using Sozobon only from a CLI, this step may
        be bypassed.

    It should be noted that during the installation of GEMENV and
    modification of your DESKTOP.INF file, the install program will
    rename your existing ROOT.ENV or DESKTOP.INF file (if any) to
    end in .BAK, to provide you with a quick recovery if anything
    goes wrong.  In addition, if you already have the Sozobon compiler
    installed on the target disk, the unpacking process will prompt
    you for permission to overwrite each file before unpacking it.
    (This is a side effect of the fact that the PDF files are really
    just self-extracting LZH archives with funny names.)

    The change to DESKTOP.INF to install MAKE as the application for
    *.MAK files is described in detail in \SOZOBON\DOC\ST_MAKE.DOC.


2.3 The GEMENV Program


    The GEMENV program installed in step 4 is a TSR that gives the
    desktop the ability to handle environment variables.  It is
    described in detail in \SOZOBON\DOC\GEMENV.DOC.  It is a
    'passive TSR'; that is, it only allocates a 1k data area in memory
    and then terminates leaving that memory resident.  It leaves no
    hooks in the operating system after the desktop is started.  The
    memory is used to store environment variables.  You may also
    double-click on GEMENV.PRG from the desktop at any time, online
    help is available in the program.

    If you decide to run without GEMENV for some reason, it will
    probably be necessary to edit the x:\SOZOBON\BIN\MAKE.INI file and
    uncomment the statements in the .INICMDS section.  In this case,
    your best bet is to install everything on your C:  drive, or
    always run the compiler only from the drive it is installed on.
    See the 'Trouble with MAKE' section, below, for more hints on how
    to run without GEMENV.  (Your best bet, by far, is to use GEMENV.)

    When you use an alternate desktop, or other programs which run
    from AUTO but take effect after the desktop is started, it may
    be necessary to ensure GEMENV runs early in the AUTO folder
    processing.  This is not a problem with GEMENV, but rather a
    side effect of the way alternate desktop programs install
    themselves into the same system vector that GEMENV uses to
    borrow control from the system for a moment just before the
    desktop starts.


2.4 Desktop Installation Procedure


    To use Sozobon C from the desktop, perform the following steps:

    1.  Unpack the entire distribution archive to any disk you
        want, but unpack all the files to the same folder.

    2.  Run INSTALL.PRG.  See the description in section 2.2, above.
        For use from the GEM desktop, you should generally allow all
        the installation steps to run.

    3.  At this point, if you are using an alternate desktop, take
        whatever manual steps are necessary to correspond to the
        INSTALL.PRG steps that were bypassed.  (IE, configure your
        environment variables as described in the CLI installation,
        below, and install MAKE.TTP as the application for .MAK files).

    4.  Reboot, to make the GEMENV program and new DESKTOP.INF file
        install themselves in the system.

    5.  Open a window on \SOZOBON\EXAMPLES and double-click on
        MAKEFILE.MAK.  This will run a series of tests on the
        compiler.  See the 'In Case of Difficulties' section, below,
        if the tests don't work.  Some of the tests create GEM
        programs, but they are not run from the makefile because GEM
        programs can't be started from a .TTP.  After they are
        compiled, just double-click on them from the desktop.  (The
        GEM programs are generated into their own folders inside the
        EXAMPLES folder.)


2.5 CLI Installation Procedure


    To use Sozobon C from a command shell (such as Gulam), perform the
    following steps:

    1.  Unpack the entire distribution archive to any disk you
        want, but unpack all the files to the same folder.

    2.  Run INSTALL.PRG.  See the description in section 2.2, above.
        To use the compiler from a command shell, you should generally
        set the GEMENV and DESKTOP.INF installation steps to BYPASS.

    3.  Using whatever method is provided by your CLI, set the
        following environment variables:

            PATH=C:\;x:\SOZOBON\BIN\
            INCLUDE=x:\SOZOBON\INCLUDE\
            LIB=x:\SOZOBON\LIB\
            BUFSIZE=4096
            TMP=r:\

        The TMP variable is optional.  If you have a fast device such
        as a ramdisk, you can use it for intermediate files by putting
        its drive letter in the TMP= variable.

        For the PATH variable, the path listed above may be added to
        your existing path list, separated with commas or semicolons.
        The trailing slash on the pathnames is optional -- include
        them or not based on what your other software prefers.  (Note
        that GEM itself *really* likes to see C:\ as the first path
        in the PATH= list!  If you use GEM, it's best to ensure that
        C:\ is always first.)

        The BUFSIZE value may be set to anything between 1024 and 32512,
        in multiples of 512.  If you have the memory to spare, 8k or
        16k works well.

    4.  Enter whatever command needed to make \SOZOBON\EXAMPLES the
        current directory, and type MAKE.  This will run a series of
        tests on the installation.  Part of the testing includes
        compiling GEM programs, but they are not run automatically
        from the makefile.


3.0 In Case of Difficulties


    Most problems with Sozobon come from two sources: 1) trouble in
    your makefile, and 2) the compiler can't find its support files.


3.1 Trouble with MAKE


    For makefile troubles, about the best advice I can offer is to
    read MAKE.DOC and ST_MAKE.DOC about 20 times, and rely heavily on
    the stuff in the examples directory.  Remember that the '-p' and
    '-d' MAKE options can be useful in debugging problems in your
    makefiles.  Also remember that if you are running MAKE from the
    desktop, you can hold down either SHIFT key while clicking on the
    .MAK file to get prompted for options.

    If double-clicking on a .MAK file doesn't cause MAKE.TTP to run,
    double-check your DESKTOP.INF file (see ST_MAKE.DOC for details
    on the DESKTOP.INF installation line). If MAKE.TTP starts, but
    warns that it can't find MAKE.INI, check your PATH= environment
    variable, or create a C:\SOZOBON\BIN dir and put MAKE.INI in
    there.  If make runs, but reports trouble finding the the Sozobon
    compiler programs, check the contents of the MAKE.INI file,
    especially the pathnames in the .INICMDS area.


3.2 Trouble with Environment Variables


    When the compiler has trouble finding its support files, it almost
    always comes down to trouble with your environment variables.
    Since the GEM desktop doesn't directly support env vars, this used
    to be 99% of everyone's Sozobon troubles.  With the new GEMENV
    program, this trouble basically disappears.  Even without help
    from GEMENV, this release of Sozobon is pretty good at finding its
    pieces.  It will search in the \SOZOBON path of the current drive,
    and if that fails, it will look for C:\SOZOBON paths.  This
    implies that if you don't want to use GEMENV for some reason, you
    can always install the compiler on the C: drive and expect things
    to work no matter what drive your source code is on.

    To make debugging the path-related problems a little easier, a
    program is included in the \SOZOBON\SPECIAL directory, called
    NAMETRAK.PRG.  When you run this program, it installs itself into
    the DOS vector and logs to the printer all file-related activity.
    Often, by installing NAMETRAK and then running the Sozobon
    compiler, you can find out where it is looking for files and
    either move everything to there (a kind of crude solution!) or
    make adjustments in your env vars.  You must reboot your machine
    to de-install the NAMETRAK program.

    Another debugging program, SHOWENV.TOS, simply displays to the
    screen the contents of all the environment variables currently in
    effect.  Whatever you see here is what the compiler and MAKE will
    see when they are run.  This is a normal program, not a TSR.


4.0 Roadmap


    This section provides an overview of the Sozobon directory
    structure and points out some important files.  When the
    packed data files are unpacked, they create the following
    directory structure:

        drive:
          \SOZOBON          - The Sozobon root, no files here.
            \BIN            - The executables.
            \INCLUDE        - The C header files for #include.
            \LIB            - The runtime libs and startup files.
            \DOC            - Documentation for everything.
            \EXAMPLES       - Example programs.
            \SPECIAL        - Desktop assists and troubleshooting.


  \SOZOBON\BIN


    This directory contains all the executables to run Sozobon C,
    including MAKE, and including the MAKE.INI file required to supply
    MAKE with rules appropriate to compiling Sozobon C programs.  If
    you have a consolidated \BIN directory elsewhere in your system,
    and you feel brave, you can copy the contents of the \SOZOBON\BIN
    directory to your single \BIN directory, adjust your PATH=
    statement accordingly, and run.  (This is what I do.)  However,
    this sort of messing around with the Sozobon structure is not for
    the faint-hearted or easily-frustrated programmer.  (On the other
    hand, this sort of messing around may be *required* for floppy
    disk users.)


  \SOZOBON\INCLUDE


    This directory holds all the header files for Sozobon C (except
    those you write yourself for your own applications -- those would
    be in the same directory as the application source code).  The
    files in this directory are originally from the dLibs12
    distribution package that corresponds to Sozobon C, and from the
    GemFast GEM programming library package.

    If you have your own system of library files and headers, or if
    you modify any of the delivered headers, it is recommended that
    you create a new folder for them.  If you do this, set the
    INCLUDE= environment variable to contain the pathname of your
    folder followed by the \SOZOBON\INCLUDE folder (separate the two
    pathnames with a semicolon).  Keeping this separation will ensure
    that you don't lose your modifications when upgrading to a new
    version of Sozobon or dLibs.


  \SOZOBON\LIB


    This directory contains the runtime libraries that are linked with
    your program by LD in the final stage of a compile.  The dlibs.a
    file contains the bulk of the runtime support.  The libm.a file
    contains floating-point math support, and is needed only when you
    use floating point variables in your program.  The vdifast.a and
    aesfast.a files contain the GEM runtime libraries, they are needed
    only when you write GEM programs.  In addition, the runtime
    startup files that are linked ahead of your program are located
    here, including the source code.  The startup files, and the
    situations they are good for, are as follows:

        DSTART.O    - Standard (ie, huge) runtime startup, for use
                      with dlibs.a.  This is required if you use
                      stream I/O (fopen, fclose, printf, etc).

        APSTART.O   - A stripped-down startup file useful for GEM
                      programming.  This startup will give you
                      command-line arguments (argc/argv), but will
                      not automatically open or close stream I/O.
                      The argc/argv support in this startup file
                      does NOT include XARGS support!

        MINSTART.O  - A very small startup file useful primarily for
                      desk accessories and GEM programs that don't
                      need argc/argv.  This startup can also be used
                      to create a program that runs as either a .PRG
                      or .ACC when you rename the program file.

    The notes about extended or modified files under \SOZOBON\INCLUDE
    above apply to this directory as well.  It is safer to create a
    new directory for your extensions to prevent troubles when
    upgrading.  If you do this, be sure to modify the LIB= env var.


  \SOZOBON\DOC


    This directory contains all the documentation in the Sozobon
    system including a copy of the document you are reading now.

    The documents are:

        SOZOBON.DOC   The docs originally released with Sozobon, but
                      modified a bit for this release.  This doc may
                      contain references for tools not included in
                      this release because they are rarely used.  This
                      is where you'll find references for all the
                      command-line options of the various compiler pieces.
                      This also has an overall revision history of all
                      the compiler pieces at the end.

        DLIBS.DOC     The runtime library reference. This documents
                      all the typical C functions such as fopen(),
                      strcpy(), and so on.

        MAKE.DOC      Documents for the MAKE utility.  MAKE.DOC is a
        ST_MAKE.DOC   general overview of MAKE for those unfamiliar
                      with it. ST_MAKE.DOC describes implementation
                      and ST-related features, and has the STMAKE
                      revision history notes.

        GEMENV.DOC    Docs for the GEMENV TSR program, and some
                      discussion of environment variables in general.

        GEMFBIND.DOC  The installation and overview document for the
                      GemFast runtime libraries.

        GEMUTIL.DOC   Descriptions of the GemFast utility functions.

        GEMXTEND.DOC  Descriptions of extensions made by Atari and Ian
                      to the GEM programming environment.

        GEMF_V16.DOC  Cumulative release notes for GemFast.


  \SOZOBON\EXAMPLES


    This directory contains example source code and makefiles used in
    testing the installation of the compiler.  The source code in this
    directory is all public domain, and may be copied into your own
    programs at will.  Each of the example programs listed below has a
    makefile associated with it, and in some cases, custom header
    files and RSC files.  The example programs are:

        HELLO.C       The obligatory Hello World program.
        FPMATH.C      Some tests using floating-point math.
        MINICOLR.C    An example that runs as an accessory or program.
        WINDXMP2.C    A GEM program with a window and some neat stuff.

        MAKEFILE.MAK  A makefile which calls MAKE recursively to
                      compile all the sample programs.


5.0 Credits and Disclaimers


    This version of Sozobon C is released on an as-is basis, under the
    terms of the original Sozobon, Ltd. copyright, which still
    applies.  This is a modified version of Sozobon C, but that does
    not imply any loss or reduction of rights to the original
    copyright holders.  The authors assume no responsibility for the
    consequences of using this software, including, but not limited
    to, responsibility for your mental health. <grin>  No warranties
    of any sort, express or implied, are made about this software or
    its suitability for a particular purpose.  Besides, I ain't got no
    money, so suing me would be a real waste of your time.

    The original Sozobon C was created by Tony Andrews, Johann Ruegg,
    and Joe Treat.  This modified version was done by Ian Lepore.  The
    dlibs runtime library was done by Dale Schumaker.  Beta testing of
    this modified release was done by Bob Goff and Mike Dorman.  I
    want the world to be well aware that a lot effort by a lot of
    folks went into this project before I ever got my hands on it.  I
    can't thank them enough for making it all possible.

    Everything in this distribution package which is wholly my own
    work (GemFast, GEMENV, STMAKE) is hereby placed into the public
    domain.  You may copy, modify, distribute, or otherwise use these
    portions of the work in any way you please, including the
    inclusion into other works, public domain or commercial.  In
    particular, I'd like to see GEMENV get wide distribution.  If you
    do modify and redistribute any of my works, I'd appreciate it if
    they are clearly marked as modifications, so I won't go nuts
    trying to support something that's been customized.

    This release of Sozobon is being distributed initally via the BIX
    online system, and I will do my best to provide what support I can
    on BIX.  I'm not available on any of the other networks at this
    time.  Other than the fact that I hang out there, there is no
    official connection between BIX and this software, however.


    Oh--and in case you ever wondered:  Sozobon is No Bozos, backwards.


    - Ian Lepore (BIX userid 'ianl')
      Moderator, BIX atari.st conference
      07/18/91


(end of document)